<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Noble Engine API reference</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
	<link rel="icon" href="favicon.ico">
</head>
<body>

<div id="container">

<div id="main">


<!-- Menu -->

<div id="navigation">
	<a href="../index.html"><div class="logo">
		<h1>Noble Engine</h1>
	</div></a>

		<div class="nav-module">
			<h2>Noble.Animation</h2>
			<ul>
					<h3>Setup </h3>
					<ul>
							<li><a href="#Noble.Animation.new">.new</a></li>
							<li><a href="#animation:addState">animation:addState</a></li>
					</ul>
					<h3>Properties </h3>
					<ul>
							<li><a href="#animation.current">animation.current</a></li>
							<li><a href="#animation.currentName">animation.currentName</a></li>
							<li><a href="#animation.currentFrame">animation.currentFrame</a></li>
							<li><a href="#animation.direction">animation.direction</a></li>
					</ul>
					<h3>Methods </h3>
					<ul>
							<li><a href="#animation:setState">animation:setState</a></li>
							<li><a href="#animation:draw">animation:draw</a></li>
							<li><a href="#animation:drawFrame">animation:drawFrame</a></li>
					</ul>
					<h3>Constants </h3>
					<ul>
							<li><a href="#Noble.Animation.DIRECTION_RIGHT">.DIRECTION_RIGHT</a></li>
							<li><a href="#Noble.Animation.DIRECTION_LEFT">.DIRECTION_LEFT</a></li>
					</ul>
			</ul>
		</div>


	<div class="nav-modules">
			<div class="nav-kind">
					<h3>Modules</h3>
					<ul>
								<li><a href="../modules/Noble.html">Noble</a></li>
								<li><span class="selected">Noble.Animation</span></li>
								<li><a href="../modules/Noble.Bonk.html">Noble.Bonk</a></li>
								<li><a href="../modules/Noble.GameData.html">Noble.GameData</a></li>
								<li><a href="../modules/Noble.Input.html">Noble.Input</a></li>
								<li><a href="../modules/Noble.Menu.html">Noble.Menu</a></li>
								<li><a href="../modules/Noble.Settings.html">Noble.Settings</a></li>
								<li><a href="../modules/Noble.Text.html">Noble.Text</a></li>
								<li><a href="../modules/Noble.Transition.html">Noble.Transition</a></li>
								<li><a href="../modules/Ease.html">Ease</a></li>
					</ul>
			</div>
			<div class="nav-kind">
					<h3>Classes</h3>
					<ul>
								<li><a href="../classes/NobleScene.html">NobleScene</a></li>
								<li><a href="../classes/NobleSprite.html">NobleSprite</a></li>
					</ul>
			</div>
			<div class="nav-kind">
					<h3>Examples</h3>
					<ul>
								<li><a href="../examples/SceneTemplate.lua.html">SceneTemplate.lua</a></li>
					</ul>
			</div>
	</div>

</div>

<div id="content">

		<h1>Noble.Animation</h1>
		<p>Animation states using a spritesheet/imagetable.</p>
		<p> Ideal for use with <a href="../classes/NobleSprite.html#">NobleSprite</a> objects. Suitable for other uses as well.</p>

		<hr/>

			<h2 class="section-header "><a name="Setup"></a>Setup </h2>
			<!--  -->
			<dl class="function">
					<dt>
						<a name = "Noble.Animation.new"></a>
						<span class="item-name">Noble.Animation.new(__view)<span>
					</dt>
					<dd>
						Create a new animation "state machine".  This function is called automatically when creating a new <a href="../classes/NobleSprite.html#">NobleSprite</a>.

								<h3>Parameters</h3>
							<ul class="parameters">
													<li><span class="parameter">__view</span>
															<span class="types"><span class="type">string</span></span>
														<br/>
														 This can be: the path to a spritesheet image file or an image table object (<code>Graphics.imagetable</code>). See Playdate SDK docs for imagetable file naming conventions.
													</li>
							</ul>

							<h3>Returns</h3>
								<ol>

										<code>animation</code>, a new animation object.
								</ol>


							<h3>See</h3>
							<ul>
									<a href="../classes/NobleSprite.html#noblesprite:init">NobleSprite:init</a>
							</ul>

							<h3>Usage</h3>
								<pre class="example"><span class="keyword">local</span> myHero = <span class="function-name">MyHero</span>(<span class="string">"path/to/spritesheet"</span>)</pre>
								<pre class="example"><span class="comment">-- When extending NobleSprite (recommended), you don't call Noble.Animation.new(),
</span><span class="comment">-- but you do feed its __view argument into MySprite.super.init()...
</span>MyHero = {}
<span class="function-name">class</span>(<span class="string">"MyHero"</span>).<span class="function-name">extends</span>(NobleSprite)

<span class="keyword">function</span> MyHero:<span class="function-name">init</span>()
	MyHero.super.<span class="function-name">init</span>(self, <span class="string">"assets/images/Hero"</span>)
	<span class="comment">-- ...
</span>	<span class="comment">-- A new NobleSprite creates a Noble.Animation object named "self.animation"
</span>	self.animation:<span class="function-name">addState</span>(<span class="string">"idle"</span>, <span class="number">1</span>, <span class="number">30</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"jump"</span>, <span class="number">31</span>, <span class="number">34</span>, <span class="string">"float"</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"float"</span>, <span class="number">35</span>, <span class="number">45</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"turn"</span>, <span class="number">46</span>, <span class="number">55</span>, <span class="string">"idle"</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"walk"</span>, <span class="number">56</span>, <span class="number">65</span>)
	<span class="comment">-- ...
</span><span class="keyword">end</span></pre>
								<pre class="example"><span class="keyword">local</span> myAnimation = Noble.Animation.<span class="function-name">new</span>(<span class="string">"path/to/spritesheet"</span>)</pre>
								<pre class="example"><span class="comment">-- When extending playdate.graphics.Sprite, Noble.Animation.new() must be called manually...
</span>MyHero = {}
<span class="function-name">class</span>(<span class="string">"MyHero"</span>).<span class="function-name">extends</span>(Graphics.sprite)

<span class="keyword">function</span> MyHero:<span class="function-name">init</span>()
	MyHero.super.<span class="function-name">init</span>(self)
	<span class="comment">-- ...
</span>	self.animation = Noble.Animation.<span class="function-name">new</span>(<span class="string">"assets/images/Hero"</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"idle"</span>, <span class="number">1</span>, <span class="number">30</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"jump"</span>, <span class="number">31</span>, <span class="number">34</span>, <span class="string">"float"</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"float"</span>, <span class="number">35</span>, <span class="number">45</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"turn"</span>, <span class="number">46</span>, <span class="number">55</span>, <span class="string">"idle"</span>)
	self.animation:<span class="function-name">addState</span>(<span class="string">"walk"</span>, <span class="number">56</span>, <span class="number">65</span>)
	<span class="comment">-- ...
</span><span class="keyword">end</span></pre>

					</dd>
					<dt>
						<a name = "animation:addState"></a>
						<span class="item-name">animation:addState(__name, __startFrame, __endFrame, __next[, __loop=true], __onComplete[, __frameDuration=1])<span>
					</dt>
					<dd>
						Add an animation state.  The first state added will be the default set for this animation.</p>

<p> <strong>NOTE:</strong> Added states are first-degree member objects of your Noble.Animation object, so do not use names of already existing methods/properties ("current", "draw", etc.).

								<h3>Parameters</h3>
							<ul class="parameters">
													<li><span class="parameter">__name</span>
															<span class="types"><span class="type">string</span></span>
														<br/>
														 The name of the animation, this is also used as the key for the animation.
													</li>
													<li><span class="parameter">__startFrame</span>
															<span class="types"><span class="type">integer</span></span>
														<br/>
														 This is the first frame of this animation in the imagetable/spritesheet
													</li>
													<li><span class="parameter">__endFrame</span>
															<span class="types"><span class="type">integer</span></span>
														<br/>
														 This is the final frame of this animation in the imagetable/spritesheet
													</li>
													<li><span class="parameter">__next</span>
															<span class="types"><span class="type">string</span></span>
														<br/>
														 By default, animation states will loop, but if you want to sequence an animation, enter the name of the next state here.
													</li>
													<li><span class="parameter">__loop</span>
															<span class="types"><span class="type">boolean</span></span>
															<span class="default">= <span class="value">true</span> (default)</span>
														<br/>
														 If you want a state to "freeze" on its final frame, instead of looping, enter <code>false</code> here.
													</li>
													<li><span class="parameter">__onComplete</span>
														<br/>
														 This function will run when this animation is complete. Be careful when using this on a looping animation!
													</li>
													<li><span class="parameter">__frameDuration</span>
															<span class="types"><span class="type">integer</span></span>
															<span class="default">= <span class="value">1</span> (default)</span>
														<br/>
														 This is the number of ticks between each frame in this animation. If not specified, it will be set to 1.
													</li>
							</ul>




							<h3>Usage</h3>
								<pre class="example"><span class="comment">-- You can reference an animation's state's properties using bog-standard lua syntax:
</span>
animation.idle.startFrame		<span class="comment">-- 30
</span>animation.walk.endFrame			<span class="comment">-- 65
</span>animation.[<span class="string">"walk"</span>].endFrame		<span class="comment">-- 65
</span>animation.jump.name				<span class="comment">-- "jump"
</span>animation.[<span class="string">"jump"</span>].<span class="global">next</span>			<span class="comment">-- "float"
</span>animation.idle.<span class="global">next</span>				<span class="comment">-- nil</span></pre>

					</dd>
			</dl>
			<h2 class="section-header "><a name="Properties"></a>Properties </h2>
			<!--  -->
			<dl class="function">
					<dt>
						<a name = "animation.current"></a>
						<span class="item-name">animation.current<span>
					</dt>
					<dd>
						The currently set animation state. </p>

<p> This is intended as <code>read-only</code>. You should not modify this property directly.




							<h3>See</h3>
							<ul>
									<a href="../modules/Noble.Animation.html#animation:setState">setState</a>
							</ul>


					</dd>
					<dt>
						<a name = "animation.currentName"></a>
						<span class="item-name">animation.currentName<span>
					</dt>
					<dd>
						The name of the current animation state.  Calling this instead of <code>animation.current.name</code> is <em>just</em> a little faster.</p>

<p> This is intended as <code>read-only</code>. You should not modify this property directly.






					</dd>
					<dt>
						<a name = "animation.currentFrame"></a>
						<span class="item-name">animation.currentFrame<span>
					</dt>
					<dd>
						The current frame of the animation.  This is the index of the imagetable, not the frame of the current state.</p>

<p> Most of the time, you should not modify this directly, although you can if you're feeling saucy and are prepared for unpredictable results.




							<h3>See</h3>
							<ul>
									<a href="../modules/Noble.Animation.html#animation:draw">draw</a>
							</ul>


					</dd>
					<dt>
						<a name = "animation.direction"></a>
						<span class="item-name">animation.direction<span>
					</dt>
					<dd>
						This controls the flipping of the image when drawing.  DIRECTION<em>RIGHT is unflipped, DIRECTION</em>LEFT is flipped on the X axis.





							<h3>Usage</h3>
								<pre class="example"><span class="keyword">function</span> MyHero:<span class="function-name">goLeft</span>()
	self.animation.direction = Noble.Animation.DIRECTION_LEFT
	<span class="comment">-- ...
</span><span class="keyword">end</span></pre>

					</dd>
			</dl>
			<h2 class="section-header "><a name="Methods"></a>Methods </h2>
			<!--  -->
			<dl class="function">
					<dt>
						<a name = "animation:setState"></a>
						<span class="item-name">animation:setState(__animationState[, __continuous=false], __unlessThisState)<span>
					</dt>
					<dd>
						Sets the current animation state.  This can be run in a object's <code>update</code> method because it only changes the animation state if the new state is different from the current one.

								<h3>Parameters</h3>
							<ul class="parameters">
													<li><span class="parameter">__animationState</span>
															<span class="types"><span class="type">string</span> or <span class="type">Noble.Animation</span></span>
														<br/>
														 The name of the animation to set. You can pass the name of the state, or the object itself.
													</li>
													<li><span class="parameter">__continuous</span>
															<span class="types"><span class="type">boolean</span></span>
															<span class="default">= <span class="value">false</span> (default)</span>
														<br/>
														 Set to true if your new state's frames line up with the previous one's, i.e.: two walk cycles but one is wearing a cute hat!
													</li>
													<li><span class="parameter">__unlessThisState</span>
															<span class="types"><span class="type">string</span> or <span class="type">Noble.Animation</span></span>
														<br/>
														 If this state is the current state, do not set the new one.
													</li>
							</ul>




							<h3>Usage</h3>
								<pre class="example">animation:<span class="function-name">setState</span>(<span class="string">"walk"</span>)</pre>
								<pre class="example">animation:<span class="function-name">setState</span>(animation.walk)</pre>
								<pre class="example">animation:<span class="function-name">setState</span>(animation.walkNoHat)
<span class="comment">--
</span>animation:<span class="function-name">setState</span>(animation.walkYesHat, <span class="keyword">true</span>)</pre>
								<pre class="example"><span class="keyword">function</span> MyHero:<span class="function-name">update</span>()
	<span class="comment">-- Input
</span>	<span class="comment">-- ...
</span>
	<span class="comment">-- Physics/collisions
</span>	<span class="comment">-- ...
</span>
	<span class="comment">-- Animation states
</span>	<span class="keyword">if</span> (grounded) <span class="keyword">then</span>
		<span class="keyword">if</span> (turning) <span class="keyword">then</span>
			self.animation:<span class="function-name">setState</span>(self.animation.turn)
		<span class="keyword">elseif</span> (<span class="global">math</span>.<span class="function-name">abs</span>(self.velocity.x) &gt; <span class="number">15</span>) <span class="keyword">then</span>
			self.animation:<span class="function-name">setState</span>(self.animation.walk, <span class="keyword">false</span>, self.animation.turn)
		<span class="keyword">else</span>
			self.animation:<span class="function-name">setState</span>(self.animation.idle, <span class="keyword">false</span>, self.animation.turn)
		<span class="keyword">end</span>
	<span class="keyword">else</span>
		self.animation:<span class="function-name">setState</span>(self.animation.jump, <span class="keyword">false</span>, self.animation.float)
	<span class="keyword">end</span>

	groundedLastFrame = grounded
<span class="keyword">end</span></pre>

					</dd>
					<dt>
						<a name = "animation:draw"></a>
						<span class="item-name">animation:draw([__x=0[, __y=0[, __advance=true]]])<span>
					</dt>
					<dd>
						Draw the current frame. </p>

<p> When attached to a NobleSprite, this is called by <code>NobleSprite:draw()</code> when added to a scene. For non-NobleSprite sprites, put this method inside your sprite's <code>draw()</code> method, or inside <a href="../classes/NobleScene.html#noblescene:update">NobleScene:update</a>.

								<h3>Parameters</h3>
							<ul class="parameters">
													<li><span class="parameter">__x</span>
															<span class="types"><span class="type">number</span></span>
															<span class="default">= <span class="value">0</span> (default)</span>
														<br/>



													</li>
													<li><span class="parameter">__y</span>
															<span class="types"><span class="type">number</span></span>
															<span class="default">= <span class="value">0</span> (default)</span>
														<br/>



													</li>
													<li><span class="parameter">__advance</span>
															<span class="types"><span class="type">boolean</span></span>
															<span class="default">= <span class="value">true</span> (default)</span>
														<br/>
														 Advances to the next frame after drawing this one. Noble.Animation is frame-based, not "delta time"-based, so its speed is dependent on your game's framerate.
													</li>
							</ul>




							<h3>Usage</h3>
								<pre class="example"><span class="keyword">function</span> MySprite:<span class="function-name">draw</span>()
	animation:<span class="function-name">draw</span>()
<span class="keyword">end</span></pre>
								<pre class="example"><span class="keyword">function</span> MyScene:<span class="function-name">update</span>()
	animation:<span class="function-name">draw</span>(<span class="number">100</span>,<span class="number">100</span>)
<span class="keyword">end</span></pre>

					</dd>
					<dt>
						<a name = "animation:drawFrame"></a>
						<span class="item-name">animation:drawFrame(__frameNumber[, __stateName=self.currentName[, __x=0[, __y=0[, __direction=self.direction]]]])<span>
					</dt>
					<dd>
						Sometimes, you just want to draw a specific frame.
 Use this for objects or sprites that you want to control outside of update loops, such as score counters, flipbook-style objects that respond to player input, etc.

								<h3>Parameters</h3>
							<ul class="parameters">
													<li><span class="parameter">__frameNumber</span>
															<span class="types"><span class="type">integer</span></span>
														<br/>
														 The frame to draw from the current state. This is not an imagetable index. Entering <code>1</code> will draw the selected state's <code>startFrame</code>.
													</li>
													<li><span class="parameter">__stateName</span>
															<span class="types"><span class="type">string</span></span>
															<span class="default">= <span class="value">self.currentName</span> (default)</span>
														<br/>
														 The specific state to pull the __frameNumber from.
													</li>
													<li><span class="parameter">__x</span>
															<span class="types"><span class="type">number</span></span>
															<span class="default">= <span class="value">0</span> (default)</span>
														<br/>



													</li>
													<li><span class="parameter">__y</span>
															<span class="types"><span class="type">number</span></span>
															<span class="default">= <span class="value">0</span> (default)</span>
														<br/>



													</li>
													<li><span class="parameter">__direction</span>
															<span class="default">= <span class="value">self.direction</span> (default)</span>
														<br/>
														 Override the current direction.
													</li>
							</ul>





					</dd>
			</dl>
			<h2 class="section-header "><a name="Constants"></a>Constants </h2>
			<!--  -->
			<dl class="function">
					<dt>
						<a name = "Noble.Animation.DIRECTION_RIGHT"></a>
						<span class="item-name">Noble.Animation.DIRECTION_RIGHT<span>
					</dt>
					<dd>
						A re-contextualized instance of <code>playdate.graphics.kImageUnflipped</code>






					</dd>
					<dt>
						<a name = "Noble.Animation.DIRECTION_LEFT"></a>
						<span class="item-name">Noble.Animation.DIRECTION_LEFT<span>
					</dt>
					<dd>
						A re-contextualized instance of <code>playdate.graphics.kImageFlippedX</code>






					</dd>
			</dl>


</div> <!-- id="content" -->

</div> <!-- id="main" -->

<div id="about">
	<span><a href="https://github.com/NobleRobot/NobleEngine">Noble Engine</a> by Mark LaCroix, <a href="https://noblerobot.com">Noble Robot</a></span>
	<span style="float:right;">
		Documentation created using <a href="https://github.com/stevedonovan/LDoc">LDoc 1.5.0</a>.
	</span>
</div> <!-- id="about" -->

</div> <!-- id="container" -->

</body>
</html>

